How to Create a Walkthrough with VICE's Event History
=====================================================

1. Basics:
----------
VICE supports recording an arbitrary session on the emulated machine and
playing back this session later. This is done by saving a snapshot at the beginning
of the recording session and then remembering all the user interaction such as
keyboard and joystick input. We call this an 'event history'.
The main purpose for having an event history is to create game sessions, e.g. recording 
how to solve a game. An example walkthrough for the well known game "Fort Apocalypse" is
available.
This brief document will advise you how to record and playback such a session.
Although it is based on the WinVICE x64 release and its user interface, histories may be
transferred to other machines and other ports that support event history, e.g. the
Unix port.

2. Recommended Settings
-----------------------
When using the event history feature it is possible that the playback session
differs from what was done at recording time. This might arise due to a problem 
in the initial snapshot or settings.
Here are some suggestions to minimize the chance of failures in the session:
a. Reset to default settings.
b. Choose refresh rate 1/1.
c. Choose joystick and Video/Doublesize settings as desired or needed.
d. SID engine must be reSID (which is the default).
e. Choose Drive settings/Idle method: None
Do not change any settings during recording or playback!

3. Recorded Events
------------------
The following is a list of the user interaction that will be recorded:
- Joystick movement and button
- Keyboard
- Resetting the machine (hard and soft)
- Attaching or detaching disk/tape images (see 8. Limitations)
- Datasette controls

4. Recording an Event History
-----------------------------
Recording an event history will create one or two files for a snapshot and
the list of the user events. First, create an empty directory in which these
files are to be saved and then select this directory and the name of the 
snapshot files via 'Snapshot//Select History files/directory'. 
Next, attach the disk or tape image with the game you want to record and load and
run the game.
Start recording via 'Snapshot//Start/Stop Recording History'.
Play the game. All actions will be recorded.
After the game is finished, stop recording via 'Snapshot//Start/Stop
Recording History'. The selected directory should now contain the two
snapshot files (default ist start.vsf and end.vsf). 

5. Setting and Returning to Milestones
--------------------------------------
It is difficult to finish a game in one sitting and noone wants to
record all their mistakes and lost lives. Use the milestone feature in a
recording session in the following way:
Set a milestone when you have finished a level or completed a task
('Snapshot//Set recording milestone' or ALT-E). This will save the event
history and a snapshot of the machine to the file end.vsf but recording will
continue.
Return to the last milestone when you have made a mistake or lost a life
('Snapshot//Return to milestone' or ALT-U). This will reset the game and the
event history to the last milestone snapshot so that you can try again.

6. Continuing an Event History
------------------------------
If you have stopped a recording session and want to continue it later, you
should create a backup of your start.vsf and end.vsf files first to avoid
overwriting them by accident.
Then change the event history start mode: 'Snapshot//Recording start mode//Load
existing snapshot'. When you start recording now, you will continue where the
session was stopped last time.
Another way of continuing an existing history is to start somewhere inside the
history (e.g. you have recorded 10 minutes of a game and later recognize that you
made a mistake after 6 minutes that makes it impossible to finish the game).
For this you have to select the start mode 'Overwrite playback'. Now you can
start the playback with 'Snapshot//Start/Stop Playback History' and when you
reach the point where you want to change the history you can directly switch to
recording via 'Snapshot//Start/Stop Recording History'.

7. Playing Back an Event History
--------------------------------
To play back an event history, select the directory with the history files
start.vsf and end.vsf via 'Snapshot//Select History directory' and start the
playback with 'Snapshot//Start/Stop Playback History'. Enjoy!
During playback any user interaction is disabled.
The playback stops when the end of the session is reached or if 
'Snapshot//Select History directory' is selected again.

8. Limitations and Suggestions
------------------------------
a. Snapshot files will be quite big (>1MB) if a disk image has been attached. 
If possible, use PRG or T64 images to reduce the size of snapshot files.
b. Snapshots may not be 100% accurate even with all the recommended settings.
